.-
help for ^btscs^
.-

BTSCS: A Binary Time-Series--Cross-Section Data Analysis Utility
----------------------------------------------------------------

^btscs^ event time-series-unit cross-section-unit1 [cross-section-unit2]
    [^if^ exp] [^in^ range] [^,^ ^g^enerate(^newvar^) ^d^ummy(^stub^)
    ^nspl^ine(^#^knots) ^lspl^ine(^#,...,#^) ^f^ailure]

Description
-----------

^btscs^ allows the user to easily compute the length of non-eventful
binary spells (i.e., the length of the sequence of zeros that precede the
current observation).  For first events, the variable generated will
equal ^0^.

^btscs^ can also produce the set of natural cubic spline and/or temporal
dummy variables associated with non-eventful binary spells -- variables
that can be used to account for duration dependence in a regression
(Beck, Katz, and Tucker 1998).

^btscs^ provides users with the option to generate several additional
variables useful for BTSCS logit analysis (i.e., first failure marker,
number of previous failures counter, and a time until failure counter).


Assumptions
-----------

1.  The event of interest must be binary (0/1-- no more than one measured
    event in each time period);

2.  There must be at least one cross-sectional variable specified but
    no more than two;

3.  Observations that are not equally spaced (i.e., 1990(obs1), 1991(obs2),
    1996(obs3)) are treated as a continuation of the non-eventful binary
    spell.


Options
-------

^generate(^newvar^)^ is not optional; it specifies the name of the new
        spell-identification variable to be created.

^dummy(^stub^)^  is optional; it specifies a stub-name for the newly
        generated corresponding spell-identification dummy variables.
        ^btscs^ will generate the dummy variables newvar1, newvar2, ... ,
        newvarK. Note that the creation of the K temporal dummy variables
        will use up lots of memory.

^nspline(^#^knots)^  is optional; it creates a truncated power basis for a
        natural cubic spline in ^newvar^-- the spell-identification
        variable.  It creates one new variable for each interior knot, named
        _spline1, _spline2,..., etc.  ^^#^knots^ specifies the number of
        interior knots (Sasieni, 1994).

^lspline(^#,...,#^)^ is optional; ^#,...,#^ specifies the location
        of the interior knots (Sasieni, 1994).

^failure^  is optional; it creates a number of discrete-time failure
        identification variables (users should be especially cognizant
        of censoring issues):

        ^_frstfl^   -- a first failure identification marker
        ^_prefail^  -- the number of previous failures
        ^_tuntilf^  -- time until failure  


Example 1 (one cross-sectional unit)
------------------------------------

  . ^btscs war year state, g(peaceyrs)^
  . ^btscs war year state, g(peaceyrs) d(k)^
  . ^btscs war year state, g(peaceyrs) d(k) f^
  . ^btscs war year state, g(peaceyrs) nspline(3)^
  . ^btscs war year state, g(peaceyrs) lspline(1,4,7)^
  . ^btscs war year state if year<1850, g(peaceyrs)^

where:

^war^ is the variable that records the event or dependent variable
of interest;

^year^ is the variable that records the temporal unit for each observation;

^state^ is the variable that contains information on the
cross-sectional unit;

^peaceyrs^ is the spell-identifier counter (created by ^btscs^) that
marks the number of years since the last event of interest;

^d(k)^ produces the spell-identification dummy variables;

^nspline(3)^ produces three spell-identification natural cubic spline
         variables -- _spline1, _spline2, and _spline3 (with three interior
         knots placed at equally spaced intervals);

^lspline(1,4,7)^ produces three spell-identification natural cubic spline
         variables -- _spline1, _spline2, and _spline3 (with knots located at
         1, 4, and 7 years of peace);

^f^ produces:

^_frstfl^ is coded as ^1^ to indicate the first failure for the
unit-of-analysis;

^_prefail^  counts the number of previous failures (events of interest);

^_tuntilf^  counts the time until failure (event occurrence).



Example 2 (two cross-sectional units)
-------------------------------------

  . ^btscs war year statea stateb, g(peaceyrs)^
  . ^btscs war year statea stateb, g(peaceyrs) d(k)^
  . ^btscs war year statea stateb, g(peaceyrs) d(k) f^
  . ^btscs war year statea stateb, g(peaceyrs) nspline(3)^
  . ^btscs war year statea stateb, g(peaceyrs) lspline(1,4,7)^
  . ^btscs war year statea stateb if year>1875 & year<1914, g(peaceyrs)^

where:

^war^ is the variable that records the event or dependent variable
of interest;

^year^ is the variable that records the temporal unit for each observation;

^statea^ is the variable that contains information on the first
cross-sectional unit in a dyad;

^stateb^ is the variable that contains information on the second
cross-sectional unit in a dyad;

^peaceyrs^ is the spell-identifier counter (created by ^btscs^) that
marks the number of years since the last event of interest;

^d(k)^ produces the spell-identification dummy variables;

^nspline(3)^ produces three spell-identification natural cubic spline
         variables -- _spline1, _spline2, and _spline3 (with three interior
         knots placed at equally spaced intervals);

^lspline(1,4,7)^ produces three spell-identification natural cubic spline
         variables -- _spline1, _spline2, and _spline3 (with knots located at
         1, 4, and 7 years of peace);

^f^ produces:

^_frstfl^ is coded as ^1^ to indicate the first failure for the
unit-of-analysis;

^_prefail^  counts the number of previous failures (events of interest);

^_tuntilf^  counts the time until failure (event occurrence).


References
----------

    Beck, Nathaniel, Katz, Jonathan N., and Richard Tucker. 1998.
    ``Taking Time Seriously in Binary Time-Series--Cross-Section Analysis."
    American Journal of Political Science 42(4):1260-1288.

    Sasieni, Peter. 1994. snp7: ``Natural Cubic Splines."
    Stata Technical Bulletin 22: 19-22.


Author
------

    Richard Tucker
    John M. Olin Institute for Strategic Studies
    Harvard University
    420 Coolidge Hall
    Cambridge, MA 02138
    rtucker@@data.fas.harvard.edu


Acknowledgements
----------------

    This program is the product of a collaborative research effort with
    Neal Beck and Jonathan Katz.  Beck and Katz are, however, absolved
    from any Stata programming sins committed here.  Nick Cox and Paul Lin
    made invaluable programming suggestions and are also excused from any
    remaining errors or inefficiencies.  Robert Bates, Andrew Enterline,
    Kristian Gleditsch, Macartan Humphreys, David Leblang, Curtis Peet,
    Karen Rasler, Marc Simon, Randy Siverson, and Michael Tomz tested early
    versions and suggested several ways to improve the program.  Finally, I
    am especially grateful for the extraordinary computer support provided
    by Micah Altman, Gary King, Yi Wang, and William Wei of the Harvard-MIT
    Data Center.


